Windows 10: SDK

This guide provides information on architecture and installation of Windows 10 SDK .

Architecture Description

Overview

This is a high-level architecture of the universal Windows 10 software development kit (SDK). In some cases, it is detailed at the class level.

This content is meant to give clients an understanding of the Windows 10 SDKs.

Central SDK class

The central SDK class serves as the entry point for all SDK interactions. It includes the following functionality:

  • Configure logging

  • Access default API client

  • Request builder factory methods

Construct API requests (builders)

All API requests are constructed using the builder pattern. There are several request builders that provide API endpoint abstractions.

  • RequestBuilder: a base class for all builders. It includes common functionality as well as the ability to add any arbitrary key and value pairs to a request.

  • RecsForPlacementsBuilder: the recsForPlacements builder.

  • RecsUsingStrategyBuilder: the recsUsingStrategy builder.

  • UserPreferenceBuilder: the user/preferences read and write builder.

  • UserProfileBuilder: the userProfile builder.

  • PersonalizeBuilder: the builder for personalize API calls.

  • GetProductsBuilder: the builder for getProducts API calls.

All builders have type-safe methods for setting values. Builders also have a build method that produces an instance of the ApiRequestclass that is sent as the final request. There are helper methods for common use cases that create preconfigured builders. This is covered in the next section.

Builder helper methods

The SDK class contains several factory methods that create preconfigured request builders for common API use cases. These methods are separated into two groups:

  • Fetching: this includes requests that expect a response. For example, this includes recommended products.

  • Tracking: this includes "fire and forget" requests. In other words, the request is sent, and it does not expect a response.

Networking

Network operations performed by the Windows 10 SDK use System.Net.WebRequest for sending requests. It also uses Windows.Networking.Connectivity.NetworkInformation to manage network reachability. All calls are HTTP GET, and all responses are JSON. There are a limited number of endpoints and paths.

API client

The ApiClient is central to the SDK. It handles all API interactions at the HTTP level by taking request information, executing HTTP calls at the same time, and responding with parsed domain objects. It is possible to create a standalone instance of this class, but it is better to use the DefaultClient located on the SDK class.

API requests

API requests originate from request builders as raw ApiRequest objects, and then passed to the SendRequest method in the ApiClient. Each request object contains properties representing the HTTP path of the request, parameters to send, a parser object, and an authorization type.

Connectivity

In low or no network connectivity scenarios, the SDK does not queue or retry failed requests for the majority of calls. If there is no network connectivity, requests are not attempted at all, and appropriate error message are reported to the calling code.

Click tracking (also known as product view tracking) is an exception. For click tracking, failed requests are queued, and then retried when network connectivity is restored. For more information, see the TrackProductView method in the ApiClient.

Logging

The SDK creates console logs via System.Diagnostics.Debug.OutputDebugString. It is configurable with the standard log levels: trace, debug, info, warn, error, off. By default logging is set to "off" so that it does not cause overhead of logging for production releases. The Log class is where all logging logic is stored.

Error conditions and handling

The SDK uses exceptions to provide information about errors:

  • System.ArgumentException: the arguments provided are invalid.

  • System.ArgumentNullException: one of the provided arguments must have a value.

  • System.FormatException: the API returns JSON with an invalid format.

  • System.Net.WebException: there is a problem with connectivity.

  • ApiException: the API returns JSON with an error code and a message. This commonly happens when the request contains incorrect parameters.

Security

By default, all SDK requests are performed using HTTPS, and include API authentication parameters to ensure a maximum security level. If supported, OAuth1.0 is used to sign requests. The SDK does not store data to disk.